<?php
/***************************************************************************
                                    Lib1.php
                                 --------------
  
       A PHP library used as a reference for Mdoc class usage and test. 

       $Author: jmfaure $
       $Id: Lib1.php,v 1.1.1.1 2006/01/05 10:37:20 jmfaure Exp $

 **************************************************************************/
 
// The class file can start with some code and comments which are just ignored by Mdoc parsing
//if (realpath($_SERVER['SCRIPT_FILENAME']) == __FILE__) die("FILE ACCESS METHOD NOT ALLOWED");

/**
 * Typical documented library, can be used as a code documenting tutorial.
 *
 * Every code documenting bloc, like this one, has the same format; the 
 * very first line is the "short description", following lines up to 
 * first @info is the "long description". Every @info comment starts a 
 * line with @ (more precisely \n * @ sequence); they are also called
 * active comments (sometimes written @ctive comments).
 *
 * The long description is optional.
 *
 * The long description can have some "display" formating block, such as
 * the [example] one or the [code] one.
 *
 * @warning   the @info fields must not have multiple entries in one
 *            documenting comment
 * @lib       Lib1
 * @version   1.0
 * @date      28 Aug 2005
 * @author    JM Faure <jmfaure@users.sourceforge.net> 
 */

/**
 * Constants can be declared in a block.
 *
 * The constant block has the standard code documenting block format. The
 * inline comments are used to document constant individualy (this is a 
 * format which suits well constants defined as a serie). These subcomments 
 * are optional.
 *
 * @experimental
 */
define("LIBT_CONST_ONE", 1);    // case flag ONE
define("LIBT_CONST_TWO", 2);    // case flag TWO
define("LIBT_CONST_THREE", 3);  // case flag THREE

/**
 * Constants can be declared with single documenting.
 *
 * Individual constant comment provides long description for every constant,
 * which makes you choose for block or individual constant documenting.
 *
 */
define("LIBT_ERRMSG_1", "A classical error message " . 
                        "which stands onto three " . 
                        "lines to be defined.");

/**
 * A method example with 3 parameters.
 *
 * The three parameters have different declaration patterns.
 *
 * @experimental
 * @param (string) $p1 the first parameter
 * @param (int) $p2 the second parameter
 * @param (bool) $p3 the 3rd parameter
 * @return (void)
 */
function f3param($p1, $p2, $p3 = true) {

  // Print the 3 parameters
  echo $p1 . "\n";
  echo $p2 . "\n";
  echo $p3 . "\n";

  return true;
}

/**
 * A method with parameters passed by reference.
 *
 * This comment line is to avoid the notice in log.
 * @warning  unstable
 * @param (string) $p1 the 1st parameter
 * @param (bool) $p2 the 2nd parameter
 *                   has a two-line comment
 * @return (string) the function result
 */
function fpbyref(& $p1, &$p2) {

  // No comment!
  return $p1;
}

/**
 * A method with a lot of description and @info items.
 *
 * Long description of func3 method is spread onto
 * three
 * lines.
 *
 * @warning  unstable
 * @forfun  one line,
 *          two lines.
 * @param (int) $p1 the first parameter
 * @param (mixed) $p2 the title of text (string)
 *                    or false (bool) to get all
 * @param (string) $p3 the third parameter
 *                  is commented onto
 *                  three lines
 * @param (array) $p4 the a structured list:
 *                    'name' => a name
 *                    'address' => an address
 *                    'city' => a city name
 * @return (void) if echo flag $p1 is true
 *                a line of comment to test parsing
 *         (string) the printable solution if echo flag is false (default)
 */
function flotdesc($p1, $p2="a string", $p3 = "another string", $p4) {

  if ($p1) {
    return;
  } else {
    return "whatever";
  }
}
?>
